<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Basic JMS API Concepts - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level3"><a href="bncdr.html">Overview of the JMS API</a></p>
<p class="toc level4"><a href="bncdr.html#bncds">What Is Messaging?</a></p>
<p class="toc level4"><a href="bncdr.html#bncdt">What Is the JMS API?</a></p>
<p class="toc level4"><a href="bncdr.html#bncdu">When Can You Use the JMS API?</a></p>
<p class="toc level4"><a href="bncdr.html#bncdw">How Does the JMS API Work with the Java EE Platform?</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Basic JMS API Concepts</a></p>
<p class="toc level4"><a href="#bncdy">JMS API Architecture</a></p>
<p class="toc level4"><a href="#bncea">Messaging Domains</a></p>
<p class="toc level5"><a href="#bnceb">Point-to-Point Messaging Domain</a></p>
<p class="toc level5"><a href="#bnced">Publish/Subscribe Messaging Domain</a></p>
<p class="toc level5"><a href="#bncef">Programming with the Common Interfaces</a></p>
<p class="toc level4 tocsp"><a href="#bnceg">Message Consumption</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnceh.html">The JMS API Programming Model</a></p>
<p class="toc level4"><a href="bnceh.html#bncej">JMS Administered Objects</a></p>
<p class="toc level5"><a href="bnceh.html#bncek">JMS Connection Factories</a></p>
<p class="toc level5"><a href="bnceh.html#bncel">JMS Destinations</a></p>
<p class="toc level4 tocsp"><a href="bnceh.html#bncem">JMS Connections</a></p>
<p class="toc level4"><a href="bnceh.html#bncen">JMS Sessions</a></p>
<p class="toc level4"><a href="bnceh.html#bnceo">JMS Message Producers</a></p>
<p class="toc level4"><a href="bnceh.html#bncep">JMS Message Consumers</a></p>
<p class="toc level5"><a href="bnceh.html#bnceq">JMS Message Listeners</a></p>
<p class="toc level5"><a href="bnceh.html#bncer">JMS Message Selectors</a></p>
<p class="toc level4 tocsp"><a href="bnceh.html#bnces">JMS Messages</a></p>
<p class="toc level5"><a href="bnceh.html#bncet">Message Headers</a></p>
<p class="toc level5"><a href="bnceh.html#bncev">Message Properties</a></p>
<p class="toc level5"><a href="bnceh.html#bncew">Message Bodies</a></p>
<p class="toc level4 tocsp"><a href="bnceh.html#bncey">JMS Queue Browsers</a></p>
<p class="toc level4"><a href="bnceh.html#bncez">JMS Exception Handling</a></p>
<p class="toc level3 tocsp"><a href="bncfu.html">Creating Robust JMS Applications</a></p>
<p class="toc level4"><a href="bncfu.html#bncfv">Using Basic Reliability Mechanisms</a></p>
<p class="toc level5"><a href="bncfu.html#bncfw">Controlling Message Acknowledgment</a></p>
<p class="toc level5"><a href="bncfu.html#bncfy">Specifying Message Persistence</a></p>
<p class="toc level5"><a href="bncfu.html#bncfz">Setting Message Priority Levels</a></p>
<p class="toc level5"><a href="bncfu.html#bncga">Allowing Messages to Expire</a></p>
<p class="toc level5"><a href="bncfu.html#bncgb">Creating Temporary Destinations</a></p>
<p class="toc level4 tocsp"><a href="bncfu.html#bncgc">Using Advanced Reliability Mechanisms</a></p>
<p class="toc level5"><a href="bncfu.html#bncgd">Creating Durable Subscriptions</a></p>
<p class="toc level5"><a href="bncfu.html#bncgh">Using JMS API Local Transactions</a></p>
<p class="toc level3 tocsp"><a href="bncgl.html">Using the JMS API in Java EE Applications</a></p>
<p class="toc level4"><a href="bncgl.html#bncgm">Using <tt>@Resource</tt> Annotations in Enterprise Bean or Web Components</a></p>
<p class="toc level4"><a href="bncgl.html#bncgn">Using Session Beans to Produce and to Synchronously Receive Messages</a></p>
<p class="toc level5"><a href="bncgl.html#bncgo">Resource Management</a></p>
<p class="toc level5"><a href="bncgl.html#bncgp">Transactions</a></p>
<p class="toc level4 tocsp"><a href="bncgl.html#bncgq">Using Message-Driven Beans to Receive Messages Asynchronously</a></p>
<p class="toc level4"><a href="bncgl.html#bncgs">Managing Distributed Transactions</a></p>
<p class="toc level4"><a href="bncgl.html#bncgt">Using the JMS API with Application Clients and Web Components</a></p>
<p class="toc level3 tocsp"><a href="bncgu.html">Further Information about JMS</a></p>
<p class="toc level2 tocsp"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bncdr.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnceh.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bncdx"></a><h2>Basic JMS API Concepts</h2>
<a name="indexterm-2306"></a><p>This section introduces the most basic JMS API concepts, the ones you must
know to get started writing simple application clients that use the JMS API.</p>

<p>The next section introduces the JMS API programming model. Later sections cover more
advanced concepts, including the ones you need to write applications that use message-driven
beans.</p>



<a name="bncdy"></a><h3>JMS API Architecture</h3>
<a name="indexterm-2307"></a><p>A JMS application is composed of the following parts.</p>


<ul><li><p><a name="indexterm-2308"></a>A <b>JMS provider</b> is a messaging system that implements the JMS interfaces and provides administrative and control features. An implementation of the Java EE platform includes a JMS provider.</p>

</li>
<li><p><b>JMS clients</b> are the programs or components, written in the Java programming language, that produce and consume messages. Any Java EE application component can act as a JMS client.</p>

</li>
<li><p><a name="indexterm-2309"></a><b>Messages</b> are the objects that communicate information between JMS clients.</p>

</li>
<li><p><a name="indexterm-2310"></a><b>Administered objects</b> are preconfigured JMS objects created by an administrator for the use of clients. The two kinds of JMS administered objects are destinations and connection factories, which are described in <a href="bnceh.html#bncej">JMS Administered Objects</a>.</p>

</li></ul>
<p><a href="#bncdz">Figure&nbsp;45-2</a> illustrates the way these parts interact. Administrative tools allow you to bind
destinations and connection factories into a JNDI namespace. A JMS client can then
use resource injection to access the administered objects in the namespace and then establish
a logical connection to the same objects through the JMS provider.</p>

<a name="bncdz"></a><p class="caption">Figure&nbsp;45-2 JMS API Architecture</p><img src="figures/jms-architecture.gif" alt="Diagram of JMS API architecture, showing administrative tool, JMS client, JNDI namespace, and JMS provider"></img>

<a name="bncea"></a><h3>Messaging Domains</h3>
<a name="indexterm-2311"></a><a name="indexterm-2312"></a><p>Before the JMS API existed, most messaging products supported either the <b>point-to-point</b> or
the <b>publish/subscribe</b> approach to messaging. The JMS specification provides a separate domain for
each approach and defines compliance for each domain. A stand-alone JMS provider can
implement one or both domains. A Java EE provider must implement both domains.</p>

<p>In fact, most implementations of the JMS API support both the point-to-point and
the publish/subscribe domains, and some JMS clients combine the use of both domains
in a single application. In this way, the JMS API has extended the
power and flexibility of messaging products.</p>

<p>The JMS specification goes one step further: It provides common interfaces that enable
you to use the JMS API in a way that is not
specific to either domain. The following subsections describe the two messaging domains and
then describe the use of the common interfaces.</p>



<a name="bnceb"></a><h4>Point-to-Point Messaging Domain</h4>
<a name="indexterm-2313"></a><a name="indexterm-2314"></a><p>A point-to-point (PTP) product or application is built on the concept of message
<b>queues</b>, senders, and receivers. Each message is addressed to a specific queue, and
receiving clients extract messages from the queues established to hold their messages. Queues
retain all messages sent to them until the messages are consumed or until
the messages expire.</p>

<p>PTP messaging has the following characteristics and is illustrated in <a href="#bncec">Figure&nbsp;45-3</a>.</p>

<a name="bncec"></a><p class="caption">Figure&nbsp;45-3 Point-to-Point Messaging</p><img src="figures/jms-pointToPoint.gif" alt="Diagram of point-to-point messaging, showing Client 1 sending a message to a queue, and Client 2 consuming and acknowledging the message"></img>
<ul><li><p>Each message has only one consumer.</p>

</li>
<li><p>A sender and a receiver of a message have no timing dependencies. The receiver can fetch the message whether or not it was running when the client sent the message.</p>

</li>
<li><p>The receiver acknowledges the successful processing of a message.</p>

</li></ul>
<p>Use PTP messaging when every message you send must be processed successfully by
one consumer.</p>



<a name="bnced"></a><h4>Publish/Subscribe Messaging Domain</h4>
<a name="indexterm-2315"></a><a name="indexterm-2316"></a><p>In a publish/subscribe (pub/sub) product or application, clients address messages to a <b>topic</b>,
which functions somewhat like a bulletin board. Publishers and subscribers are generally anonymous
and can dynamically publish or subscribe to the content hierarchy. The system takes care
of distributing the messages arriving from a topic&rsquo;s multiple publishers to its multiple
subscribers. Topics retain messages only as long as it takes to distribute them
to current subscribers.</p>

<p>Pub/sub messaging has the following characteristics.</p>


<ul><li><p>Each message can have multiple consumers.</p>

</li>
<li><p>Publishers and subscribers have a timing dependency. A client that subscribes to a topic can consume only messages published after the client has created a subscription, and the subscriber must continue to be active in order for it to consume messages.</p>

</li></ul>
<p>The JMS API relaxes this timing dependency to some extent by allowing subscribers
to create <b>durable subscriptions</b>, which receive messages sent while the subscribers are not active.
Durable subscriptions provide the flexibility and reliability of queues but still allow clients to
send messages to many recipients. For more information about durable subscriptions, see <a href="bncfu.html#bncgd">Creating Durable Subscriptions</a>.</p>

<p>Use pub/sub messaging when each message can be processed by zero, one, or
many consumers. <a href="#bncee">Figure&nbsp;45-4</a> illustrates pub/sub messaging.</p>

<a name="bncee"></a><p class="caption">Figure&nbsp;45-4 Publish/Subscribe Messaging</p><img src="figures/jms-publishSubscribe.gif" alt="Diagram of pub/sub messaging, showing Client 1 publishing a message to a topic, and the message being delivered to two subscribers to the topic"></img>

<a name="bncef"></a><h4>Programming with the Common Interfaces</h4>
<a name="indexterm-2317"></a><p>Version 1.1 of the JMS API allows you to use the same
code to send and receive messages under either the PTP or the pub/sub
domain. The destinations that you use remain domain-specific, and the behavior of the
application will depend in part on whether you are using a queue or
a topic. However, the code itself can be common to both domains, making
your applications flexible and reusable. This tutorial describes and illustrates these common interfaces.</p>



<a name="bnceg"></a><h3>Message Consumption</h3>
<a name="indexterm-2318"></a><p>Messaging products are inherently asynchronous: There is no fundamental timing dependency between the
production and the consumption of a message. However, the JMS specification uses this
term in a more precise sense. Messages can be consumed in either of
two ways:</p>


<ul><li><p><a name="indexterm-2319"></a><a name="indexterm-2320"></a><b>Synchronously</b>: A subscriber or a receiver explicitly fetches the message from the destination by calling the <tt>receive</tt> method. The <tt>receive</tt> method can block until a message arrives or can time out if a message does not arrive within a specified time limit.</p>

</li>
<li><p><a name="indexterm-2321"></a><a name="indexterm-2322"></a><b>Asynchronously</b>: A client can register a <b>message listener</b> with a consumer. A message listener is similar to an event listener. Whenever a message arrives at the destination, the JMS provider delivers the message by calling the listener&rsquo;s <tt>onMessage</tt> method, which acts on the contents of the message.</p>

</li></ul>

         </div>
         <div class="navigation">
             <a href="bncdr.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnceh.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

